<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>zlib::inflate_stream::write</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
<link rel="up" href="../boost__beast__zlib__inflate_stream.html" title="zlib::inflate_stream">
<link rel="prev" href="reset/overload2.html" title="zlib::inflate_stream::reset (2 of 2 overloads)">
<link rel="next" href="../boost__beast__zlib__kind.html" title="zlib::kind">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reset/overload2.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost__beast__zlib__inflate_stream.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../boost__beast__zlib__kind.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="beast.ref.boost__beast__zlib__inflate_stream.write"></a><a class="link" href="write.html" title="zlib::inflate_stream::write">zlib::inflate_stream::write</a>
</h5></div></div></div>
<p>
          <a class="indexterm" name="idp141413648"></a>
Decompress input and produce output.
        </p>
<h6>
<a name="beast.ref.boost__beast__zlib__inflate_stream.write.h0"></a>
          <span class="phrase"><a name="beast.ref.boost__beast__zlib__inflate_stream.write.synopsis"></a></span><a class="link" href="write.html#beast.ref.boost__beast__zlib__inflate_stream.write.synopsis">Synopsis</a>
        </h6>
<pre class="programlisting"><span class="keyword">void</span>
<span class="identifier">write</span><span class="special">(</span>
    <span class="identifier">z_params</span><span class="special">&amp;</span> <span class="identifier">zs</span><span class="special">,</span>
    <span class="identifier">Flush</span> <span class="identifier">flush</span><span class="special">,</span>
    <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">);</span>
</pre>
<h6>
<a name="beast.ref.boost__beast__zlib__inflate_stream.write.h1"></a>
          <span class="phrase"><a name="beast.ref.boost__beast__zlib__inflate_stream.write.description"></a></span><a class="link" href="write.html#beast.ref.boost__beast__zlib__inflate_stream.write.description">Description</a>
        </h6>
<p>
          This function decompresses as much data as possible, and stops when the
          input buffer becomes empty or the output buffer becomes full. It may introduce
          some output latency (reading input without producing any output) except
          when forced to flush.
        </p>
<p>
          One or both of the following actions are performed:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              Decompress more input starting at <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_in</span></code>
              and update <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_in</span></code> and <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">avail_in</span></code>
              accordingly. If not all input can be processed (because there is not
              enough room in the output buffer), <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_in</span></code>
              is updated and processing will resume at this point for the next call.
            </li>
<li class="listitem">
              Provide more output starting at <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_out</span></code>
              and update <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_out</span></code> and <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">avail_out</span></code>
              accordingly. <code class="computeroutput"><span class="identifier">write</span></code>
              provides as much output as possible, until there is no more input data
              or no more space in the output buffer (see below about the flush parameter).
            </li>
</ul></div>
<p>
          Before the call, the application should ensure that at least one of the
          actions is possible, by providing more input and/or consuming more output,
          and updating the values in <code class="computeroutput"><span class="identifier">zs</span></code>
          accordingly. The application can consume the uncompressed output when it
          wants, for example when the output buffer is full (<code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">avail_out</span>
          <span class="special">==</span> <span class="number">0</span></code>),
          or after each call. If <code class="computeroutput"><span class="identifier">write</span></code>
          returns no error and with zero <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">avail_out</span></code>,
          it must be called again after making room in the output buffer because
          there might be more output pending.
        </p>
<p>
          The flush parameter may be <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">none</span></code>,
          <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">sync</span></code>, <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">finish</span></code>,
          <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">block</span></code>, or <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">trees</span></code>.
          <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">sync</span></code> requests to flush as much output
          as possible to the output buffer. <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">block</span></code>
          requests to stop if and when it gets to the next deflate block boundary.
          When decoding the zlib or gzip format, this will cause <code class="computeroutput"><span class="identifier">write</span></code>
          to return immediately after the header and before the first block. When
          doing a raw inflate, <code class="computeroutput"><span class="identifier">write</span></code>
          will go ahead and process the first block, and will return when it gets
          to the end of that block, or when it runs out of data.
        </p>
<p>
          The <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">block</span></code> option assists in appending to
          or combining deflate streams. Also to assist in this, on return <code class="computeroutput"><span class="identifier">write</span></code> will set <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">data_type</span></code>
          to the number of unused bits in the last byte taken from <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_in</span></code>,
          plus 64 if <code class="computeroutput"><span class="identifier">write</span></code> is currently
          decoding the last block in the deflate stream, plus 128 if <code class="computeroutput"><span class="identifier">write</span></code> returned immediately after decoding
          an end-of-block code or decoding the complete header up to just before
          the first byte of the deflate stream. The end-of-block will not be indicated
          until all of the uncompressed data from that block has been written to
          <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_out</span></code>. The number of unused bits may
          in general be greater than seven, except when bit 7 of <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">data_type</span></code>
          is set, in which case the number of unused bits will be less than eight.
          <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">data_type</span></code> is set as noted here every
          time <code class="computeroutput"><span class="identifier">write</span></code> returns for
          all flush options, and so can be used to determine the amount of currently
          consumed input in bits.
        </p>
<p>
          The <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">trees</span></code> option behaves as <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">block</span></code> does, but it also returns when
          the end of each deflate block header is reached, before any actual data
          in that block is decoded. This allows the caller to determine the length
          of the deflate block header for later use in random access within a deflate
          block. 256 is added to the value of <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">data_type</span></code>
          when <code class="computeroutput"><span class="identifier">write</span></code> returns immediately
          after reaching the end of the deflate block header.
        </p>
<p>
          <code class="computeroutput"><span class="identifier">write</span></code> should normally be
          called until it returns <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">end_of_stream</span></code>
          or another error. However if all decompression is to be performed in a
          single step (a single call of <code class="computeroutput"><span class="identifier">write</span></code>),
          the parameter flush should be set to <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">finish</span></code>.
          In this case all pending input is processed and all pending output is flushed;
          <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">avail_out</span></code> must be large enough to hold
          all of the uncompressed data for the operation to complete. (The size of
          the uncompressed data may have been saved by the compressor for this purpose.)
          The use of <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">finish</span></code> is not required to perform an
          inflation in one step. However it may be used to inform inflate that a
          faster approach can be used for the single call. <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">finish</span></code>
          also informs inflate to not maintain a sliding window if the stream completes,
          which reduces inflate's memory footprint. If the stream does not complete,
          either because not all of the stream is provided or not enough output space
          is provided, then a sliding window will be allocated and <code class="computeroutput"><span class="identifier">write</span></code> can be called again to continue
          the operation as if <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">none</span></code>
          had been used.
        </p>
<p>
          In this implementation, <code class="computeroutput"><span class="identifier">write</span></code>
          always flushes as much output as possible to the output buffer, and always
          uses the faster approach on the first call. So the effects of the flush
          parameter in this implementation are on the return value of <code class="computeroutput"><span class="identifier">write</span></code> as noted below, when <code class="computeroutput"><span class="identifier">write</span></code> returns early when <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">block</span></code> or <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">trees</span></code>
          is used, and when <code class="computeroutput"><span class="identifier">write</span></code>
          avoids the allocation of memory for a sliding window when <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">finsih</span></code> is used.
        </p>
<p>
          If a preset dictionary is needed after this call, <code class="computeroutput"><span class="identifier">write</span></code>
          sets <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">adler</span></code> to the Adler-32 checksum of the
          dictionary chosen by the compressor and returns <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">need_dictionary</span></code>;
          otherwise it sets <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">adler</span></code> to the Adler-32 checksum of all
          output produced so far (that is, <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">total_out</span>
          <span class="identifier">bytes</span></code>) and returns no error,
          <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">end_of_stream</span></code>, or an error code as described
          below. At the end of the stream, <code class="computeroutput"><span class="identifier">write</span></code>
          checks that its computed adler32 checksum is equal to that saved by the
          compressor and returns <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">end_of_stream</span></code>
          only if the checksum is correct.
        </p>
<p>
          This function returns no error if some progress has been made (more input
          processed or more output produced), <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">end_of_stream</span></code>
          if the end of the compressed data has been reached and all uncompressed
          output has been produced, <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">need_dictionary</span></code>
          if a preset dictionary is needed at this point, <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">invalid_data</span></code>
          if the input data was corrupted (input stream not conforming to the zlib
          format or incorrect check value), <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">stream_error</span></code>
          if the stream structure was inconsistent (for example if <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_in</span></code>
          or <code class="computeroutput"><span class="identifier">zs</span><span class="special">.</span><span class="identifier">next_out</span></code> was null), <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">need_buffers</span></code>
          if no progress is possible or if there was not enough room in the output
          buffer when <code class="computeroutput"><span class="identifier">Flush</span><span class="special">::</span><span class="identifier">finish</span></code> is used. Note that <code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">need_buffers</span></code> is not fatal, and <code class="computeroutput"><span class="identifier">write</span></code> can be called again with more input
          and more output space to continue decompressing.
        </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2016, 2017 Vinnie Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reset/overload2.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost__beast__zlib__inflate_stream.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../boost__beast__zlib__kind.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
